---
title: 'Slack'
sidebarTitle: 'Slack'
description: 'Access the Slack API in 2 minutes 💨'
---

import { StatusWidget } from "/snippets/api-down-watch/status-widget.jsx"

<StatusWidget service="slack" />

<Tabs>
  <Tab title="🚀 Quickstart">
    <Steps>
      <Step title="Create an integration">
        In Nango ([free signup](https://app.nango.dev)), go to [Integrations](https://app.nango.dev/dev/integrations) -> _Configure New Integration_ -> _Slack_.
      </Step>
      <Step title="Authorize Slack">
        Go to [Connections](https://app.nango.dev/dev/connections) -> _Add Test Connection_ -> _Authorize_, then log in to Slack. Later, you'll let your users do the same directly from your app.
      </Step>
      <Step title="Call the Slack API">
        Let's make your first request to the Slack API (fetch a list of channels in a Slack team). Replace the placeholders below with your [secret key](https://app.nango.dev/dev/environment-settings), [integration ID](https://app.nango.dev/dev/integrations), and [connection ID](https://app.nango.dev/dev/connections):
        <Tabs>
            <Tab title="cURL">

                ```bash
                curl "https://api.nango.dev/proxy/conversations.list?limit=10" \
                  -H "Authorization: Bearer <NANGO-SECRET-KEY>" \
                  -H "Provider-Config-Key: <INTEGRATION-ID>" \
                  -H "Connection-Id: <CONNECTION-ID>"
                ```

            </Tab>

            <Tab title="Node">

            Install Nango's backend SDK with `npm i @nangohq/node`. Then run:

            ```typescript
            import { Nango } from '@nangohq/node';

            const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });

            const res = await nango.get({
                endpoint: '/conversations.list',
                params: { limit: 10 },
                providerConfigKey: '<INTEGRATION-ID>',
                connectionId: '<CONNECTION-ID>'
            });

            console.log(res.data);
            ```
            </Tab>


        </Tabs>

        Or fetch credentials dynamically via the [Node SDK](/reference/sdks/node#get-a-connection-with-credentials) or [API](/reference/api/connection/get).

      </Step>
    </Steps>

    ✅ You're connected! Check the [Logs](https://app.nango.dev/dev/logs) tab in Nango to inspect requests.

    <Tip>
    Next step: [Embed the auth flow](/getting-started/quickstart/embed-in-your-app) in your app to let your users connect their Slack accounts.
    </Tip>
  </Tab>
  <Tab title="🧑‍💻 OAuth app setup">
    <Steps>
      <Step title="Create a developer account">
        Go to [Slack Developer Program signup page](https://api.slack.com/developer-program) and click Join the Program.
      </Step>
      <Step title="Create & configure a Slack app">
        1. Click on the **Your Apps** button then **Create New App**.
        2. Choose how you’d like to configure your app’s scopes and settings. You can use a manifest file or start from scratch; for a simpler flow, select **From scratch**.
        3. Add your **App name** and select a workspace to develop your app in, then click **Create App**.
        4. In the **Basic Information** tab, copy your app's `Client ID` and `Client Secret`, as you'll need them when configuring your integration in Nango.
        </Step>
        <Step title="Set up the OAuth scopes">
        1. In the left sidebar, select the **OAuth & Permissions** tab and configure the following Redirect URL: `https://api.nango.dev/oauth/callback`.
        2. Still in the **OAuth & Permissions** tab, under **Scopes**, add the scopes that are relevant to how you want to consume Slack's API.
        There are 2 types of scopes, [Bot Token Scopes](https://docs.slack.dev/reference/scopes/?token_types=Bot) and [User Token Scopes](https://docs.slack.dev/reference/scopes/?token_types=User).
        - Bot tokens represent a bot associated with an app installed in a workspace. They govern what your app can access. They will be added to Nango when creating a Slack integration.
        - User token Scopes access user data and act on behalf of users that authorize them. They will be [added](/reference/api/connect/sessions/create#body-integrations-config-defaults-key-user-scopes) to Nango when creating a Slack connection.
      </Step>
      <Step title="Create a Slack Developer Sandbox (Optional)">
        If you don't have a Slack Developer Sandbox already, head over to Slack's [Developer Program dashboard](https://api.slack.com/developer-program/dashboard) and provision one to test your integration.
      </Step>
      <Step title="Next">
        Follow the [_Quickstart_](/getting-started/quickstart).
      </Step>
    </Steps>
  </Tab>
  <Tab title="🔗 Useful links">
    | Topic | Links |
    | - | - |
    | General | [Website](https://slack.com/) |
    | | [Create a test account](https://slack.com/get-started) |
    | Developer | [API documentation](https://api.slack.com/web) |
    | | [Create a developer account](https://api.slack.com/developer-program) |
    | | [Developer console](https://api.slack.com/apps) |
    | | [Authorization documentation](https://api.slack.com/authentication/oauth-v2) |
    | | [Register an OAuth app](https://api.slack.com/apps) |
    | | [List of OAuth scopes](https://api.slack.com/scopes) |
    | | [Details on rate limits](https://api.slack.com/docs/rate-limits) |

    <Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/slack.mdx)</Note>
  </Tab>
  <Tab title="🚨 API gotchas">
    ### Bot Token vs User Token
    
    Slack issues two separate access tokens during OAuth:
    - **Bot Token** (starts with `xoxb-`): Used for actions performed by your app's bot
    - **User Token** (starts with `xoxp-`): Used for actions performed on behalf of the authorizing user
    
    **Important:** By default, Nango uses the bot token as the primary access token. This means when you make API calls through Nango's proxy, it will use the bot token by default.
    
    #### When You Need the User Token
    
    Some Slack API endpoints require user-scoped permissions and will only accept user tokens (e.g., certain user profile operations). If you try to call these endpoints with the bot token, Slack will reject the request.
    
    #### How to Use the User Token
    
    1. **Fetch the raw connection to get the user token:**
    
    ```typescript
    import { Nango } from '@nangohq/node';
    
    const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });
    
    // Fetch the connection with raw credentials
    const connection = await nango.getConnection(
      '<INTEGRATION-ID>',
      '<CONNECTION-ID>'
    );
    
    // The user token is in the raw response
    const userToken = connection.credentials.raw.authed_user?.access_token;
    ```
    
    2. **Override the authorization header when making proxy calls:**
    
    ```typescript
    // Use the user token by overriding the auth header
    const response = await nango.get({
      endpoint: '/users.profile.get',
      providerConfigKey: '<INTEGRATION-ID>',
      connectionId: '<CONNECTION-ID>',
      headers: {
        'nango-proxy-authorization': `Bearer ${userToken}`
      }
    });
    ```
    
    #### When Creating Connections in Nango
    
    If you need user tokens for your integration, you can specify [user scopes](/reference/api/connect/sessions/create#body-integrations-config-defaults-key-user-scopes) when creating a connect session:
    
    ```typescript
    const { data } = await nango.createConnectSession({
      end_user_id: '<END-USER-ID>',
      integrations_config_defaults: {
        "slack": {
          user_scopes: "users.profile:read, chat:write"
        }
      }
    });
    ```

    <Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/slack.mdx)</Note>
  </Tab>
</Tabs>

<Info>
    Questions? Join us in the [Slack community](https://nango.dev/slack).
</Info>
